/*
 * Copyright (C) 2009 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.grapevine.contact.vcard;

import java.io.IOException;
import java.io.InputStream;
import com.grapevine.contact.vcard.exception.VCardException;

public abstract class VCardParser
{

	protected boolean mCanceled;

	/**
	 * Parses the given stream and send the VCard data into VCardBuilderBase
	 * object.
	 * 
	 * Note that vCard 2.1 specification allows "CHARSET" parameter, and some
	 * career sets local encoding to it. For example, Japanese phone career uses
	 * Shift_JIS, which is formally allowed in VCard 2.1, but not recommended in
	 * VCard 3.0. In VCard 2.1, In some exreme case, some VCard may have
	 * different charsets in one VCard (though we do not see any device which
	 * emits such kind of malicious data)
	 * 
	 * In order to avoid "misunderstanding" charset as much as possible, this
	 * method use "ISO-8859-1" for reading the stream. When charset is specified
	 * in some property (with "CHARSET=..." attribute), the string is decoded to
	 * raw bytes and encoded to the charset. This method assumes that
	 * "ISO-8859-1" has 1 to 1 mapping in all 8bit characters, which is not
	 * completely sure. In some cases, this "decoding-encoding" scheme may fail.
	 * To avoid the case,
	 * 
	 * We recommend you to use VCardSourceDetector and detect which kind of
	 * source the VCard comes from and explicitly specify a charset using the
	 * result.
	 * 
	 * @param is
	 *            The source to parse.
	 * @param builder
	 *            The VCardBuilderBase object which used to construct data. If
	 *            you want to include multiple VCardBuilderBase objects in this
	 *            field, consider using {#link VCardBuilderCollection} class.
	 * @return Returns true for success. Otherwise returns false.
	 * @throws IOException
	 *             , VCardException
	 */
	public abstract boolean parse(InputStream is, VCardBuilder builder) throws IOException, VCardException;

	/**
	 * The method variants which accept charset.
	 * 
	 * RFC 2426 "recommends" (not forces) to use UTF-8, so it may be OK to use
	 * UTF-8 as an encoding when parsing vCard 3.0. But note that some Japanese
	 * phone uses Shift_JIS as a charset (e.g. W61SH), and another uses
	 * "CHARSET=SHIFT_JIS", which is explicitly prohibited in vCard 3.0
	 * specification (e.g. W53K).
	 * 
	 * @param is
	 *            The source to parse.
	 * @param charset
	 *            Charset to be used.
	 * @param builder
	 *            The VCardBuilderBase object.
	 * @return Returns true when successful. Otherwise returns false.
	 * @throws IOException
	 *             , VCardException
	 */
	public abstract boolean parse(InputStream is, String charset, VCardBuilder builder) throws IOException,
			VCardException;

	/**
	 * The method variants which tells this object the operation is already
	 * canceled. XXX: Is this really necessary?
	 * 
	 * @hide
	 */
	public abstract void parse(InputStream is, String charset, VCardBuilder builder, boolean canceled)
			throws IOException, VCardException;

	/**
	 * Cancel parsing. Actual cancel is done after the end of the current one
	 * vcard entry parsing.
	 */
	public void cancel()
	{
		mCanceled = true;
	}
}
